﻿using System;
using System.Collections.Generic;

namespace NCommet.Core.Agents
{
    /// <summary>
    /// <c>ISorter</c> defines the interface for sorting a list of items based on a field of the item's content.
    /// The field of the content must have been marked with <see cref="NCommet.Core.IndexableAttribute" />.
    /// </summary>
    public interface ISorter
    {
        /// <summary>
        /// Sorts a list of items in ascending order. The comparison is made based on
        /// the field of the item's content that's marked with
        /// <see cref="NCommet.Core.IndexableAttribute" /> of the specified <c>Key</c>.
        /// </summary>
        /// <remarks>
        /// The item list contains the item ids and not the items themselves, in order to accomodate
        /// a chain solution where the sorter receives input from the searcher interface.
        /// </remarks>
        /// <param name="ItemsToSort">A list of item ids</param>
        /// <param name="Key">The key to use for comparison. All items must have a content whose type
        /// contains a property marked with <see cref="NCommet.Core.IndexableAttribute" /> of that key.
        /// </param>
        /// <returns>An enumerable of the sorted items (in ascending order).</returns>
        IEnumerable<Item> Sort(IList<int> ItemsToSort, int Key);

        /// <summary>
        /// Sorts a list of items in ascending order. The comparison is made based on
        /// the field of the item's content that's marked with
        /// <see cref="NCommet.Core.IndexableAttribute" /> of the specified <c>Key</c>.
        /// </summary>
        /// <remarks>
        /// The item list contains the item ids and not the items themselves, in order to accomodate
        /// a chain solution where the sorter receives input from the searcher interface.
        /// </remarks>
        /// <param name="IdsToSort">A list of item ids</param>
        /// <param name="Key">The key to use for comparison. All items must have a content whose type
        /// contains a property marked with <see cref="NCommet.Core.IndexableAttribute" /> of that key.
        /// </param>
        /// <returns>A list of the sorted item ids (in ascending order).</returns>
        IList<int> SortToIds(IList<int> IdsToSort, int Key);
    }
}
